Selecting Data

Items in a listbox can be selected both through end-user interactions and programmatically. The SelectionMode property defines how the items in a listbox can be selected through end-user interactions. SelectionMode.Single (default) indicates that only one item can be selected at a time. Multiple indicates that multiple items can be selected without pressing the CTRL or SHIFT modifier keys. Extended indicates that multiple items can be selected by pressing a modifier key.

Retrieving the Selected Items

By using the BeginGetSelectedItems and EndGetSelectedItems asynchronous methods, the items that are currently selected in a listbox can be retrieved. When dealing with a local data source (i.e., "full list"), the BeginGetSelectedItems method will return immediately and the value of the IsCompleted property of the returned IAsyncResult will be true, indicating that the operation has been completed. The EndGetSelectedItems method can then be called to finalize the process and get the selected items. If a virtualized data source is used, the EndGetSelectedItems method needs to be called in the callback after verifying whether the operation completed synchronously or not.

VB.NET

Private Sub GetSelectedItems()
   Dim result As IAsyncResult = Me.listBox.BeginGetSelectedItems( New AsyncCallback( AddressOf Me.ProcessSelectedItems ), Nothing )
   If( result.IsCompleted ) Then
      Dim selectedItems As IEnumerable( Of Object ) = Me.listBox.EndGetSelectedItems( result )
   End If
End Sub
 
Private Sub ProcessSelectedItems( ByVal result As IAsyncResult )
   If( result.CompletedSynchronously ) Then
      Return
   End If
   Dim selectedItems As IEnumerable( Of Object )  = Me.listBox.EndGetSelectedItems( result )
End Sub

private void GetSelectedItems()
{
   IAsyncResult result = this.listBox.BeginGetSelectedItems( new AsyncCallback( this.ProcessSelectedItems ), null );
   if( result.IsCompleted )
      IEnumerable<object> selectedItems = this.listBox.EndGetSelectedItems( result );
}
 
private void ProcessSelectedItems( IAsyncResult result )
{
   if( result.CompletedSynchronously )
      return;
   IEnumerable<object> selectedItems = this.listBox.EndGetSelectedItems( result );
}

The SelectedItems, SelectedItem, SelectedValue, and SelectedValuePath properties should only be used with sources that are not data-virtualized (asynchronous): the BeginGetSelectedItems and EndGetSelectedItems methods should be used instead if the data source is data-virtualized (asynchronous). If used with an asynchronous source, SelectedItems will throw an exception, SelectedItem and SelectedValue will always return null, and SelectedValuePath will have no effect.

Selecting Items Programmatically

Items can be selected by adding selection ranges to a listbox's SelectedRanges property. Each range that is added to the collection represents a group of items that have matched one or more selection criteria. Programmatically, a selection range can only be created if the data it is working with is sorted. In order to sort the data, one or more SortDescription objects, which will be used to create the data query that is sent to the data source, must be provided at construction time.

A selection range defines "start" and "end" range-information dictionaries that specify the start and end points of a range of selected items (see StartRangeInfos and EndRangeInfos properties). For each start/end range-information dictionary combination that is added to the selection range, a corresponding sort description, whose PropertyName property value matches the key of the start/end range-information dictionary combination, must also be provided (see examples below).

The sort descriptions used by a selection range have no impact on how the data is actually sorted in the listbox and vice-versa.

In addition, both the start/end range-information dictionaries (i.e., StartRangeInfos and EndRangeInfos, respectively) expose an IsInclusive property that determines whether the start or end range-information dictionaries are inclusive, indicating that their values are included in the selection range (default), or if they are excluded from the selection range. These properties apply to all the range-information dictionary combinations specified in the StartRangeInfos and EndRangeInfos dictionaries.

Predicates (i.e., filter parameter in the SelectionRange ctors) are executed locally meaning that when the BeginGetSelectedItems and EndGetSelectedItems are called and a selection range that provides a predicate is used, items will be retrieved from the server in order to determine those that pass the filter.

If one or more start and end range information dictionary is provided and/or a filter expression, only the items that are not already excluded by the range information and filter expression will be retrieved.

In a virtualized environment, it is not recommended to use the filter predicate unless dealing with a very limited number of items.

Items can also be unselected by creating a selection range and setting its SelectionType property to Unselect (see Unselecting items from a selection range example below).

The following examples cover most, if not all, possible scenarios.

Selecting all items

Selecting specific items (ShipCountry = "Germany")

Selecting items within a range (ShipCountry = "A-M")

Selecting items using a filter expression (ShipVia !=3)

Selecting items using combined filter expressions (ShipVia = 3 OR OrderDate >= 2008/01/01)

Selecting items using multiple selection-range infos (ShipVia = 2 AND OrderDate = 2006)

Selecting items using a predicate delegate (ShippedDate > RequiredDate)

Selecting items using multiple selection ranges (ShipCountry = "A-D" AND ShipCountry = "M-S")

Selecting items from start to specified end point

Selecting items from specified start point to end

Unselecting items from a selection range

Selecting from and to a specific item (LOCAL LIST ONLY)

Selecting a single item from a remote data source (WCF DataServiceQuery)

Selection-Changed Notifications

Selection-changed notifications are provided via the SelectionChanged event, which is raised whenever the selection in a listbox changes, whether by end-user interaction or through programmatic modifications of the selected ranges.